home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kfiledialog.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-12  |  34.3 KB  |  990 lines
  1. // -*- c++ -*-
  2. /* This file is part of the KDE libraries
  3.     Copyright (C) 1997, 1998 Richard Moore <rich@kde.org>
  4.                   1998 Stephan Kulow <coolo@kde.org>
  5.                   1998 Daniel Grana <grana@ie.iwi.unibe.ch>
  6.                   2000,2001 Carsten Pfeiffer <pfeiffer@kde.org>
  7.                   2001 Frerich Raabe <raabe@kde.org>
  8.  
  9.     This library is free software; you can redistribute it and/or
  10.     modify it under the terms of the GNU Library General Public
  11.     License as published by the Free Software Foundation; either
  12.     version 2 of the License, or (at your option) any later version.
  13.  
  14.     This library is distributed in the hope that it will be useful,
  15.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17.     Library General Public License for more details.
  18.  
  19.     You should have received a copy of the GNU Library General Public License
  20.     along with this library; see the file COPYING.LIB.  If not, write to
  21.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22.     Boston, MA 02110-1301, USA.
  23. */
  24.  
  25. #ifndef __KFILEDIALOG_H__
  26. #define __KFILEDIALOG_H__
  27.  
  28. #include <qstring.h>
  29.  
  30. #include <kdialogbase.h>
  31. #include <kfile.h>
  32. #include <kurl.h>
  33. #include <kmimetype.h>
  34. #include <kio/jobclasses.h>
  35.  
  36. class QCheckBox;
  37. class QHBoxLayout;
  38. class QGridLayout;
  39. class QLabel;
  40. class QPopupMenu;
  41. class QVBoxLayout;
  42.  
  43. class KActionCollection;
  44. class KDirOperator;
  45. class KURLBar;
  46. class KURLComboBox;
  47. class KFileFilterCombo;
  48. class KFileView;
  49. class KFileItem;
  50. class KPushButton;
  51. class KToolBar;
  52. class KPreviewWidgetBase;
  53.  
  54. struct KFileDialogPrivate;
  55.  
  56. /**
  57.  * Provides a user (and developer) friendly way to
  58.  * select files and directories.
  59.  *
  60.  * The widget can be used as a drop in replacement for the
  61.  * QFileDialog widget, but has greater functionality and a nicer GUI.
  62.  *
  63.  * You will usually want to use one of the static methods
  64.  * getOpenFileName(), getSaveFileName(), getOpenURL()
  65.  * or for multiple files getOpenFileNames() or getOpenURLs().
  66.  *
  67.  * The dialog has been designed to allow applications to customise it
  68.  * by subclassing. It uses geometry management to ensure that subclasses
  69.  * can easily add children that will be incorporated into the layout.
  70.  *
  71.  * \image html kfiledialog.png "KDE File Dialog"
  72.  *
  73.  * @short A file selection dialog.
  74.  *
  75.  * @author Richard J. Moore <rich@kde.org>, Carsten Pfeiffer <pfeiffer@kde.org>
  76.  */
  77. class KIO_EXPORT KFileDialog : public KDialogBase
  78. {
  79.     Q_OBJECT
  80.  
  81. public:
  82.  
  83.     /**
  84.      * Defines some default behavior of the filedialog.
  85.      * E.g. in mode @p Opening and @p Saving, the selected files/urls will
  86.      * be added to the "recent documents" list. The Saving mode also implies
  87.      * setKeepLocation() being set.
  88.      *
  89.      * @p Other means that no default actions are performed.
  90.      *
  91.      * @see setOperationMode
  92.      * @see operationMode
  93.      */
  94.     enum OperationMode { Other = 0, Opening, Saving };
  95.  
  96.     /**
  97.       * Constructs a file dialog.
  98.       *
  99.       * @param startDir This can either be
  100.       *         @li The URL of the directory to start in.
  101.       *         @li QString::null to start in the current working
  102.       *            directory, or the last directory where a file has been
  103.       *            selected.
  104.       *         @li ':<keyword>' to start in the directory last used
  105.       *             by a filedialog in the same application that specified
  106.       *             the same keyword.
  107.       *         @li '::<keyword>' to start in the directory last used
  108.       *             by a filedialog in any application that specified the
  109.       *             same keyword.
  110.       *
  111.       * @param filter A shell glob or a mime-type-filter that specifies
  112.       *               which files to display.
  113.       * @param parent The parent widget of this dialog
  114.       * @param name The name of this object
  115.       * @param modal Whether to create a modal dialog or not
  116.       * See setFilter() for details on how to use this argument.
  117.       *
  118.       */
  119.     KFileDialog(const QString& startDir, const QString& filter,
  120.         QWidget *parent, const char *name,
  121.         bool modal);
  122.  
  123.     /**
  124.       * Constructs a file dialog.
  125.       *
  126.       * The parameters here are identical to the first constructor except
  127.       * for the addition of a QWidget parameter.
  128.       *
  129.       * Historical note: The original version of KFileDialog did not have this extra
  130.       * parameter. It was added later, and, in order to maintain binary compatibility,
  131.       * it was placed in a new constructor instead of added to the original one.
  132.       *
  133.       * @param startDir This can either be
  134.       *         @li The URL of the directory to start in.
  135.       *         @li QString::null to start in the current working
  136.       *             directory, or the last directory where a file has been
  137.       *             selected.
  138.       *         @li ':<keyword>' to start in the directory last used
  139.       *             by a filedialog in the same application that specified
  140.       *             the same keyword.
  141.       *         @li '::<keyword>' to start in the directory last used
  142.       *             by a filedialog in any application that specified the
  143.       *             same keyword.
  144.       *
  145.       * @param filter A shell glob or a mime-type-filter that specifies
  146.       *               which files to display.
  147.       * See setFilter() for details on how to use this argument.
  148.       *
  149.       * @param widget A widget, or a widget of widgets, for displaying custom
  150.       *               data in the dialog. This can be used, for example, to
  151.       *               display a check box with the caption "Open as read-only".
  152.       *               When creating this widget, you don't need to specify a parent,
  153.       *               since the widget's parent will be set automatically by KFileDialog.
  154.       * @param parent The parent widget of this dialog
  155.       * @param name The name of this object
  156.       * @param modal Whether to create a modal dialog or not
  157.       * @since 3.1
  158.       */
  159.     KFileDialog(const QString& startDir, const QString& filter,
  160.         QWidget *parent, const char *name,
  161.         bool modal, QWidget* widget);
  162.  
  163.  
  164.     /**
  165.      * Destructs the file dialog.
  166.      */
  167.     ~KFileDialog();
  168.  
  169.     /**
  170.      * @returns The selected fully qualified filename.
  171.      */
  172.     KURL selectedURL() const;
  173.  
  174.     /**
  175.      * @returns The list of selected URLs.
  176.      */
  177.     KURL::List selectedURLs() const;
  178.  
  179.     /**
  180.      * @returns the currently shown directory.
  181.      */
  182.     KURL baseURL() const;
  183.  
  184.     /**
  185.      * Returns the full path of the selected file in the local filesystem.
  186.      * (Local files only)
  187.      */
  188.     QString selectedFile() const;
  189.  
  190.     /**
  191.      * Returns a list of all selected local files.
  192.      */
  193.     QStringList selectedFiles() const;
  194.  
  195.     /**
  196.      * Sets the directory to view.
  197.      *
  198.      * @param url URL to show.
  199.      * @param clearforward Indicates whether the forward queue
  200.      * should be cleared.
  201.      */
  202.     void setURL(const KURL &url, bool clearforward = true);
  203.  
  204.     /**
  205.      * Sets the file name to preselect to @p name
  206.      *
  207.      * This takes absolute URLs and relative file names.
  208.      */
  209.     void setSelection(const QString& name);
  210.  
  211.     /**
  212.      * Sets the operational mode of the filedialog to @p Saving, @p Opening
  213.      * or @p Other. This will set some flags that are specific to loading
  214.      * or saving files. E.g. setKeepLocation() makes mostly sense for
  215.      * a save-as dialog. So setOperationMode( KFileDialog::Saving ); sets
  216.      * setKeepLocation for example.
  217.      *
  218.      * The mode @p Saving, together with a default filter set via
  219.      * setMimeFilter() will make the filter combobox read-only.
  220.      *
  221.      * The default mode is @p Opening.
  222.      *
  223.      * Call this method right after instantiating KFileDialog.
  224.      *
  225.      * @see operationMode
  226.      * @see KFileDialog::OperationMode
  227.      */
  228.     void setOperationMode( KFileDialog::OperationMode );
  229.  
  230.     /**
  231.      * @returns the current operation mode, Opening, Saving or Other. Default
  232.      * is Other.
  233.      *
  234.      * @see operationMode
  235.      * @see KFileDialog::OperationMode
  236.      */
  237.     OperationMode operationMode() const;
  238.  
  239.     /**
  240.      * Sets whether the filename/url should be kept when changing directories.
  241.      * This is for example useful when having a predefined filename where
  242.      * the full path for that file is searched.
  243.      *
  244.      * This is implicitly set when operationMode() is KFileDialog::Saving
  245.      *
  246.      * getSaveFileName() and getSaveURL() set this to true by default, so that
  247.      * you can type in the filename and change the directory without having
  248.      * to type the name again.
  249.      */
  250.     void setKeepLocation( bool keep );
  251.  
  252.     /**
  253.      * @returns whether the contents of the location edit are kept when
  254.      * changing directories.
  255.      */
  256.     bool keepsLocation() const;
  257.  
  258.     /**
  259.      * Sets the filter to be used to @p filter.
  260.      *
  261.      * You can set more
  262.      * filters for the user to select separated by '\n'. Every
  263.      * filter entry is defined through namefilter|text to diplay.
  264.      * If no | is found in the expression, just the namefilter is
  265.      * shown. Examples:
  266.      *
  267.      * \code
  268.      * kfile->setFilter("*.cpp|C++ Source Files\n*.h|Header files");
  269.      * kfile->setFilter("*.cpp");
  270.      * kfile->setFilter("*.cpp|Sources (*.cpp)");
  271.      * kfile->setFilter("*.cpp|" + i18n("Sources (*.cpp)"));
  272.      * kfile->setFilter("*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header files");
  273.      * \endcode
  274.      *
  275.      * Note: The text to display is not parsed in any way. So, if you
  276.      * want to show the suffix to select by a specific filter, you must
  277.      * repeat it.
  278.      *
  279.      * If the filter contains an unescaped '/', a mimetype-filter is assumed.
  280.      * If you would like a '/' visible in your filter it can be escaped with
  281.      * a '\'. You can specify multiple mimetypes like this (separated with
  282.      * space):
  283.      *
  284.      * \code
  285.      * kfile->setFilter( "image/png text/html text/plain" );
  286.      * kfile->setFilter( "*.cue|CUE\\/BIN Files (*.cue)" );
  287.      * \endcode
  288.      *
  289.      * @see filterChanged
  290.      * @see setMimeFilter
  291.      */
  292.     void setFilter(const QString& filter);
  293.  
  294.     /**
  295.      * Returns the current filter as entered by the user or one of the
  296.      * predefined set via setFilter().
  297.      *
  298.      * @see setFilter()
  299.      * @see filterChanged()
  300.      */
  301.     QString currentFilter() const;
  302.  
  303.     /**
  304.      * Sets the filter up to specify the output type.
  305.      *
  306.      * @param label the label to use instead of "Filter:"
  307.      * @param types a list of mimetypes that can be used as output format
  308.      * @param defaultType the default mimetype to use as output format.
  309.      *
  310.      * Do not use in conjunction with setFilter()
  311.      * @deprecated
  312.      */
  313.     void setFilterMimeType(const QString &label, const KMimeType::List &types, const KMimeType::Ptr &defaultType) KDE_DEPRECATED;
  314.  
  315.     /**
  316.      * Returns the mimetype for the desired output format.
  317.      *
  318.      * This is only valid if setFilterMimeType() has been called
  319.      * previously.
  320.      *
  321.      * @see setFilterMimeType()
  322.      */
  323.     KMimeType::Ptr currentFilterMimeType();
  324.  
  325.     /**
  326.      * Sets the filter up to specify the output type.
  327.      *
  328.      * @param types a list of mimetypes that can be used as output format
  329.      * @param defaultType the default mimetype to use as output format, if any.
  330.      * If @p defaultType is set, it will be set as the current item.
  331.      * Otherwise, a first item showing all the mimetypes will be created.
  332.      * Typically, @p defaultType should be empty for loading and set for saving.
  333.      *
  334.      * Do not use in conjunction with setFilter()
  335.      */
  336.     void setMimeFilter( const QStringList& types,
  337.                         const QString& defaultType = QString::null );
  338.  
  339.     /**
  340.      * The mimetype for the desired output format.
  341.      *
  342.      * This is only valid if setMimeFilter() has been called
  343.      * previously.
  344.      *
  345.      * @see setMimeFilter()
  346.      */
  347.     QString currentMimeFilter() const;
  348.  
  349.     /**
  350.      *  Clears any mime- or namefilter. Does not reload the directory.
  351.      */
  352.     void clearFilter();
  353.  
  354.     /**
  355.      * @deprecated
  356.      * Add a preview widget and enter the preview mode.
  357.      *
  358.      * In this mode
  359.      * the dialog is split and the right part contains your widget.
  360.      * This widget has to inherit QWidget and it has to implement
  361.      * a slot showPreview(const KURL &); which is called
  362.      * every time the file changes. You may want to look at
  363.      * koffice/lib/kofficecore/koFilterManager.cc for some hints :)
  364.      *
  365.      * Ownership is transferred to KFileDialog. You need to create the
  366.      * preview-widget with "new", i.e. on the heap.
  367.      */
  368.     void setPreviewWidget(const QWidget *w) KDE_DEPRECATED;
  369.  
  370.     /**
  371.      * Adds a preview widget and enters the preview mode.
  372.      *
  373.      * In this mode the dialog is split and the right part contains your
  374.      * preview widget.
  375.      *
  376.      * Ownership is transferred to KFileDialog. You need to create the
  377.      * preview-widget with "new", i.e. on the heap.
  378.      *
  379.      * @param w The widget to be used for the preview.
  380.      */
  381.    void setPreviewWidget(const KPreviewWidgetBase *w);
  382.  
  383.     /**
  384.      * Creates a modal file dialog and return the selected
  385.      * filename or an empty string if none was chosen.
  386.      *
  387.      * Note that with
  388.      * this method the user must select an existing filename.
  389.      *
  390.      * @param startDir This can either be
  391.      *         @li The URL of the directory to start in.
  392.      *         @li QString::null to start in the current working
  393.      *            directory, or the last directory where a file has been
  394.      *            selected.
  395.      *         @li ':<keyword>' to start in the directory last used
  396.      *             by a filedialog in the same application that specified
  397.      *             the same keyword.
  398.      *         @li '::<keyword>' to start in the directory last used
  399.      *             by a filedialog in any application that specified the
  400.      *             same keyword.
  401.      * @param filter This is a space separated list of shell globs.
  402.      * You can set the text to be displayed for the glob, and
  403.      * provide multiple globs.  See setFilter() for details on
  404.      * how to do this...
  405.      * @param parent The widget the dialog will be centered on initially.
  406.      * @param caption The name of the dialog widget.
  407.      */
  408.     static QString getOpenFileName(const QString& startDir= QString::null,
  409.                    const QString& filter= QString::null,
  410.                    QWidget *parent= 0,
  411.                    const QString& caption = QString::null);
  412.  
  413.  
  414.    /**
  415.      * Use this version only if you have no QWidget available as
  416.      * parent widget. This can be the case if the parent widget is
  417.      * a widget in another process or if the parent widget is a
  418.      * non-Qt widget. For example, in a GTK program.
  419.      *
  420.      * @since 3.4
  421.     */
  422.    static QString getOpenFileNameWId(const QString& startDir,
  423.                                      const QString& filter,
  424.                                      WId parent_id, const QString& caption);
  425.  
  426.     /**
  427.      * Creates a modal file dialog and returns the selected
  428.      * filenames or an empty list if none was chosen.
  429.      *
  430.      * Note that with
  431.      * this method the user must select an existing filename.
  432.      *
  433.      * @param startDir This can either be
  434.      *         @li The URL of the directory to start in.
  435.      *         @li QString::null to start in the current working
  436.      *            directory, or the last directory where a file has been
  437.      *            selected.
  438.      *         @li ':<keyword>' to start in the directory last used
  439.      *             by a filedialog in the same application that specified
  440.      *             the same keyword.
  441.      *         @li '::<keyword>' to start in the directory last used
  442.      *             by a filedialog in any application that specified the
  443.      *             same keyword.
  444.      * @param filter This is a space separated list of shell globs.
  445.      * You can set the text to be displayed for the glob, and
  446.      * provide multiple globs.  See setFilter() for details on
  447.      * how to do this...
  448.      * @param parent The widget the dialog will be centered on initially.
  449.      * @param caption The name of the dialog widget.
  450.      */
  451.     static QStringList getOpenFileNames(const QString& startDir= QString::null,
  452.                     const QString& filter= QString::null,
  453.                     QWidget *parent = 0,
  454.                     const QString& caption= QString::null);
  455.  
  456.  
  457.  
  458.     /**
  459.      * Creates a modal file dialog and returns the selected
  460.      * URL or an empty string if none was chosen.
  461.      *
  462.      * Note that with
  463.      * this method the user must select an existing URL.
  464.      *
  465.      * @param startDir This can either be
  466.      *         @li The URL of the directory to start in.
  467.      *         @li QString::null to start in the current working
  468.      *            directory, or the last directory where a file has been
  469.      *            selected.
  470.      *         @li ':<keyword>' to start in the directory last used
  471.      *             by a filedialog in the same application that specified
  472.      *             the same keyword.
  473.      *         @li '::<keyword>' to start in the directory last used
  474.      *             by a filedialog in any application that specified the
  475.      *             same keyword.
  476.      * @param filter This is a space separated list of shell globs.
  477.      * You can set the text to be displayed for the glob, and
  478.      * provide multiple globs.  See setFilter() for details on
  479.      * how to do this...
  480.      * @param parent The widget the dialog will be centered on initially.
  481.      * @param caption The name of the dialog widget.
  482.      */
  483.     static KURL getOpenURL(const QString& startDir = QString::null,
  484.                const QString& filter= QString::null,
  485.                QWidget *parent= 0,
  486.                const QString& caption = QString::null);
  487.  
  488.  
  489.  
  490.     /**
  491.      * Creates a modal file dialog and returns the selected
  492.      * URLs or an empty list if none was chosen.
  493.      *
  494.      * Note that with
  495.      * this method the user must select an existing filename.
  496.      *
  497.      * @param startDir This can either be
  498.      *         @li The URL of the directory to start in.
  499.      *         @li QString::null to start in the current working
  500.      *            directory, or the last directory where a file has been
  501.      *            selected.
  502.      *         @li ':<keyword>' to start in the directory last used
  503.      *             by a filedialog in the same application that specified
  504.      *             the same keyword.
  505.      *         @li '::<keyword>' to start in the directory last used
  506.      *             by a filedialog in any application that specified the
  507.      *             same keyword.
  508.      * @param filter This is a space separated list of shell globs.
  509.      * You can set the text to be displayed for the glob, and
  510.      * provide multiple globs.  See setFilter() for details on
  511.      * how to do this...
  512.      * @param parent The widget the dialog will be centered on initially.
  513.      * @param caption The name of the dialog widget.
  514.      */
  515.     static KURL::List getOpenURLs(const QString& startDir= QString::null,
  516.                   const QString& filter= QString::null,
  517.                   QWidget *parent = 0,
  518.                   const QString& caption= QString::null);
  519.  
  520.  
  521.  
  522.     /**
  523.      * Creates a modal file dialog and returns the selected
  524.      * filename or an empty string if none was chosen.
  525.      *
  526.      * Note that with this
  527.      * method the user need not select an existing filename.
  528.      *
  529.      * @param startDir This can either be
  530.      *         @li The URL of the directory to start in.
  531.      *         @li a relative path or a filename determining the
  532.      *             directory to start in and the file to be selected.
  533.      *         @li QString::null to start in the current working
  534.      *            directory, or the last directory where a file has been
  535.      *            selected.
  536.      *         @li ':<keyword>' to start in the directory last used
  537.      *             by a filedialog in the same application that specified
  538.      *             the same keyword.
  539.      *         @li '::<keyword>' to start in the directory last used
  540.      *             by a filedialog in any application that specified the
  541.      *             same keyword.
  542.      * @param filter This is a space separated list of shell globs.
  543.      * You can set the text to be displayed for the glob, and
  544.      * provide multiple globs.  See setFilter() for details on
  545.      * how to do this...
  546.      * @param parent The widget the dialog will be centered on initially.
  547.      * @param caption The name of the dialog widget.
  548.      */
  549.     static QString getSaveFileName(const QString& startDir= QString::null,
  550.                    const QString& filter= QString::null,
  551.                    QWidget *parent= 0,
  552.                    const QString& caption = QString::null);
  553.            
  554.                    
  555.     /**
  556.      * This function accepts the window id of the parent window, instead
  557.      * of QWidget*. It should be used only when necessary.
  558.      * @since 3.4
  559.      */         
  560.     static QString getSaveFileNameWId(const QString& dir, const QString& filter,
  561.                                      WId parent_id,
  562.                                      const QString& caption);
  563.  
  564.     /**
  565.      * Creates a modal file dialog and returns the selected
  566.      * filename or an empty string if none was chosen.
  567.      *
  568.      * Note that with this
  569.      * method the user need not select an existing filename.
  570.      *
  571.      * @param startDir This can either be
  572.      *         @li The URL of the directory to start in.
  573.      *         @li a relative path or a filename determining the
  574.      *             directory to start in and the file to be selected.
  575.      *         @li QString::null to start in the current working
  576.      *            directory, or the last directory where a file has been
  577.      *            selected.
  578.      *         @li ':<keyword>' to start in the directory last used
  579.      *             by a filedialog in the same application that specified
  580.      *             the same keyword.
  581.      *         @li '::<keyword>' to start in the directory last used
  582.      *             by a filedialog in any application that specified the
  583.      *             same keyword.
  584.      * @param filter This is a space separated list of shell globs.
  585.      * You can set the text to be displayed for the glob, and
  586.      * provide multiple globs.  See setFilter() for details on
  587.      * how to do this...
  588.      * @param parent The widget the dialog will be centered on initially.
  589.      * @param caption The name of the dialog widget.
  590.      */
  591.     static KURL getSaveURL(const QString& startDir= QString::null,
  592.                const QString& filter= QString::null,
  593.                QWidget *parent= 0,
  594.                const QString& caption = QString::null);
  595.  
  596.  
  597.     /**
  598.      * Creates a modal file dialog and returns the selected
  599.      * directory or an empty string if none was chosen.
  600.      *
  601.      * @param startDir This can either be
  602.      *         @li The URL of the directory to start in.
  603.      *         @li QString::null to start in the current working
  604.      *            directory, or the last directory where a file has been
  605.      *            selected.
  606.      *         @li ':<keyword>' to start in the directory last used
  607.      *             by a filedialog in the same application that specified
  608.      *             the same keyword.
  609.      *         @li '::<keyword>' to start in the directory last used
  610.      *             by a filedialog in any application that specified the
  611.      *             same keyword.
  612.      * @param parent The widget the dialog will be centered on initially.
  613.      * @param caption The name of the dialog widget.
  614.      */
  615.     static QString getExistingDirectory(const QString & startDir = QString::null,
  616.                     QWidget * parent = 0,
  617.                     const QString& caption= QString::null);
  618.  
  619.     /**
  620.      * Creates a modal file dialog and returns the selected
  621.      * directory or an empty string if none was chosen.
  622.      *
  623.      * Contrary to getExistingDirectory(), this method allows the
  624.      * selection of a remote directory.
  625.      *
  626.      * @param startDir This can either be
  627.      *         @li The URL of the directory to start in.
  628.      *         @li QString::null to start in the current working
  629.      *            directory, or the last directory where a file has been
  630.      *            selected.
  631.      *         @li ':<keyword>' to start in the directory last used
  632.      *             by a filedialog in the same application that specified
  633.      *             the same keyword.
  634.      *         @li '::<keyword>' to start in the directory last used
  635.      *             by a filedialog in any application that specified the
  636.      *             same keyword.
  637.      * @param parent The widget the dialog will be centered on initially.
  638.      * @param caption The name of the dialog widget.
  639.      * @since 3.1
  640.      */
  641.     static KURL getExistingURL(const QString & startDir = QString::null,
  642.                                   QWidget * parent = 0,
  643.                                   const QString& caption= QString::null);
  644.     /**
  645.      * Creates a modal file dialog with an image previewer and returns the
  646.      * selected url or an empty string if none was chosen.
  647.      *
  648.      * @param startDir This can either be
  649.      *         @li The URL of the directory to start in.
  650.      *         @li QString::null to start in the current working
  651.      *            directory, or the last directory where a file has been
  652.      *            selected.
  653.      *         @li ':<keyword>' to start in the directory last used
  654.      *             by a filedialog in the same application that specified
  655.      *             the same keyword.
  656.      *         @li '::<keyword>' to start in the directory last used
  657.      *             by a filedialog in any application that specified the
  658.      *             same keyword.
  659.      * @param parent The widget the dialog will be centered on initially.
  660.      * @param caption The name of the dialog widget.
  661.      */
  662.     static KURL getImageOpenURL( const QString& startDir = QString::null,
  663.                  QWidget *parent = 0,
  664.                  const QString& caption = QString::null );
  665.     virtual void show();
  666.  
  667.     /**
  668.      * Convenient overload of the other setMode(unsigned int) method.
  669.      */
  670.     void setMode( KFile::Mode m );
  671.  
  672.     /**
  673.      * Sets the mode of the dialog.
  674.      *
  675.      * The mode is defined as (in kfile.h):
  676.      * \code
  677.      *    enum Mode {
  678.      *         File         = 1,
  679.      *         Directory    = 2,
  680.      *         Files        = 4,
  681.      *         ExistingOnly = 8,
  682.      *         LocalOnly    = 16
  683.      *    };
  684.      * \endcode
  685.      * You can OR the values, e.g.
  686.      * \code
  687.      * KFile::Mode mode = static_cast<KFile::Mode>( KFile::Files |
  688.      *                                              KFile::ExistingOnly |
  689.      *                                              KFile::LocalOnly );
  690.      * setMode( mode );
  691.      * \endcode
  692.      */
  693.     void setMode( unsigned int m );
  694.  
  695.     /**
  696.      * Returns the mode of the filedialog.
  697.      * @see setMode()
  698.      */
  699.     KFile::Mode mode() const;
  700.  
  701.     /**
  702.      * Sets the text to be displayed in front of the selection.
  703.      *
  704.      * The default is "Location".
  705.      * Most useful if you want to make clear what
  706.      * the location is used for.
  707.      */
  708.     void setLocationLabel(const QString& text);
  709.  
  710.     /**
  711.      * Returns a pointer to the toolbar.
  712.      *
  713.      * You can use this to insert custom
  714.      * items into it, e.g.:
  715.      * \code
  716.      *      yourAction = new KAction( i18n("Your Action"), 0,
  717.      *                                this, SLOT( yourSlot() ),
  718.      *                                this, "action name" );
  719.      *      yourAction->plug( kfileDialog->toolBar() );
  720.      * \endcode
  721.      */
  722.     KToolBar *toolBar() const { return toolbar; }
  723.  
  724.     /**
  725.      * @returns a pointer to the OK-Button in the filedialog. You may use it
  726.      * e.g. to set a custom text to it.
  727.      */
  728.     KPushButton *okButton() const;
  729.  
  730.     /**
  731.      * @returns a pointer to the Cancel-Button in the filedialog. You may use
  732.      * it e.g. to set a custom text to it.
  733.      */
  734.     KPushButton *cancelButton() const;
  735.  
  736.     /**
  737.      * @returns the KURLBar object used as the "speed bar". You can add custom
  738.      * entries to it like that:
  739.      * \code
  740.      * KURLBar *urlBar = fileDialog->speedBar();
  741.      * if ( urlBar )
  742.      *     urlBar->insertDynamicItem( someURL, i18n("The URL's description") );
  743.      * \endcode
  744.      *
  745.      * Note that this method may return a null-pointer if the user configured
  746.      * to not use the speed-bar.
  747.      * @see KURLBar
  748.      * @see KURLBar::insertDynamicItem
  749.      * @since 3.2
  750.      */
  751.     KURLBar *speedBar();
  752.  
  753.     /**
  754.      * @returns a pointer to the action collection, holding all the used
  755.      * KActions.
  756.      */
  757.     KActionCollection *actionCollection() const;
  758.  
  759.     /**
  760.      * @returns the index of the path combobox so when inserting widgets into
  761.      * the dialog (e.g. subclasses) they can do so without hardcoding in an index
  762.      */
  763.     int pathComboIndex();
  764.  
  765.     /**
  766.      * This method implements the logic to determine the user's default directory
  767.      * to be listed. E.g. the documents direcory, home directory or a recently
  768.      * used directory.
  769.      * @param startDir A url/directory, to be used. May use the ':' and '::' syntax
  770.      *        as documented in the KFileDialog() constructor.
  771.      * @param recentDirClass If the ':' or '::' syntax is used, recentDirClass
  772.      *        will contain the string to be used later for KRecentDir::dir()
  773.      * @return The URL that should be listed by default (e.g. by KFileDialog or
  774.      *         KDirSelectDialog).
  775.      * @since 3.1
  776.      */
  777.     static KURL getStartURL( const QString& startDir, QString& recentDirClass );
  778.  
  779.     /**
  780.      * @internal
  781.      * Used by KDirSelectDialog to share the dialog's start directory.
  782.      */
  783.     static void setStartDir( const KURL& directory );
  784.  
  785. signals:
  786.     /**
  787.       * Emitted when the user selects a file. It is only emitted in single-
  788.       * selection mode. The best way to get notified about selected file(s)
  789.       * is to connect to the okClicked() signal inherited from KDialogBase
  790.       * and call selectedFile(), selectedFiles(),
  791.       * selectedURL() or selectedURLs().
  792.       */
  793.     void fileSelected(const QString&);
  794.  
  795.     /**
  796.       * Emitted when the user highlights a file.
  797.       */
  798.     void fileHighlighted(const QString&);
  799.  
  800.     /**
  801.      * Emitted when the user hilights one or more files in multiselection mode.
  802.      *
  803.      * Note: fileHighlighted() or fileSelected() are @em not
  804.      * emitted in multiselection mode. You may use selectedItems() to
  805.      * ask for the current highlighted items.
  806.      * @see fileSelected
  807.      */
  808.     void selectionChanged();
  809.  
  810.     /**
  811.      * Emitted when the filter changed, i.e. the user entered an own filter
  812.      * or chose one of the predefined set via setFilter().
  813.      *
  814.      * @param filter contains the new filter (only the extension part,
  815.      * not the explanation), i.e. "*.cpp" or "*.cpp *.cc".
  816.      *
  817.      * @see setFilter()
  818.      * @see currentFilter()
  819.      */
  820.     void filterChanged( const QString& filter );
  821.  
  822. protected:
  823.     KToolBar *toolbar;
  824.  
  825.     static KURL *lastDirectory;
  826.  
  827.     KURLComboBox *locationEdit;
  828.  
  829.     KFileFilterCombo *filterWidget;
  830.  
  831.     /**
  832.      * Reimplemented to animate the cancel button.
  833.      */
  834.     virtual void keyPressEvent( QKeyEvent *e );
  835.  
  836.     /**
  837.       * Perform basic initialization tasks. Called by constructors.
  838.       * @since 3.1
  839.       */
  840.     void init(const QString& startDir, const QString& filter, QWidget* widget);
  841.  
  842.     /**
  843.       * rebuild geometry management.
  844.       *
  845.       */
  846.     virtual void initGUI();
  847.  
  848.     /**
  849.      * called when an item is highlighted/selected in multiselection mode.
  850.      * handles setting the locationEdit.
  851.      */
  852.     void multiSelectionChanged();
  853.  
  854.     /**
  855.      * Reads configuration and applies it (size, recent directories, ...)
  856.      */
  857.     virtual void readConfig( KConfig *, const QString& group = QString::null );
  858.  
  859.     /**
  860.      * Saves the current configuration
  861.      */
  862.     virtual void writeConfig( KConfig *, const QString& group = QString::null );
  863.  
  864.     /**
  865.      * Reads the recent used files and inserts them into the location combobox
  866.      */
  867.     virtual void readRecentFiles( KConfig * );
  868.  
  869.     /**
  870.      * Saves the entries from the location combobox.
  871.      */
  872.     virtual void saveRecentFiles( KConfig * );
  873.  
  874.     /**
  875.      * Parses the string "line" for files. If line doesn't contain any ", the
  876.      * whole line will be interpreted as one file. If the number of " is odd,
  877.      * an empty list will be returned. Otherwise, all items enclosed in " "
  878.      * will be returned as correct urls.
  879.      */
  880.     KURL::List tokenize(const QString& line) const;
  881.  
  882.     /**
  883.      * Returns the absolute version of the URL specified in locationEdit.
  884.      * @since 3.2
  885.      */
  886.     KURL getCompleteURL(const QString&);
  887.  
  888.     /**
  889.      * Returns the filename extension associated with the currentFilter().
  890.      * QString::null is returned if an extension is not available or if
  891.      * operationMode() != Saving.
  892.      * @since 3.2
  893.      */
  894.     QString currentFilterExtension();
  895.  
  896.     /**
  897.      * Updates the currentFilterExtension and the availability of the
  898.      * Automatically Select Extension Checkbox (visible if operationMode()
  899.      * == Saving and enabled if an extension _will_ be associated with the
  900.      * currentFilter(), _after_ this call).  You should call this after
  901.      * filterWidget->setCurrentItem().
  902.      * @since 3.2
  903.      */
  904.     void updateAutoSelectExtension();
  905.  
  906.  
  907. protected slots:
  908.     void urlEntered( const KURL& );
  909.     void enterURL( const KURL& url );
  910.     void enterURL( const QString& url );
  911.     void locationActivated( const QString& url );
  912.  
  913.     /**
  914.      * @deprecated,
  915.      */
  916.     // ### remove in KDE4
  917.     void toolbarCallback(int);
  918.     /**
  919.      * @deprecated
  920.      */
  921.     // ### remove in KDE4
  922.     void pathComboChanged( const QString& );
  923.     /**
  924.      * @deprecated
  925.      */
  926.     // ### remove in KDE4
  927.     void dirCompletion( const QString& );
  928.  
  929.     void slotFilterChanged();
  930.     void fileHighlighted(const KFileItem *i);
  931.     void fileSelected(const KFileItem *i);
  932.     void slotStatResult(KIO::Job* job);
  933.     void slotLoadingFinished();
  934.  
  935.     void fileCompletion( const QString& );
  936.     /**
  937.      * @since 3.1
  938.      */
  939.     void toggleSpeedbar( bool );
  940.  
  941.     /**
  942.      * @since 3.4
  943.      */
  944.     void toggleBookmarks(bool show);
  945.  
  946.     /**
  947.      * @deprecated
  948.      */
  949.     virtual void updateStatusLine(int dirs, int files);
  950.  
  951.     virtual void slotOk();
  952.     virtual void accept();
  953.     virtual void slotCancel();
  954.  
  955.     void slotAutoSelectExtClicked();
  956.     void addToRecentDocuments();
  957.     void initSpeedbar();
  958.  
  959. private slots:
  960.     void slotLocationChanged( const QString& text );
  961.  
  962. private:
  963.     KFileDialog(const KFileDialog&);
  964.     KFileDialog operator=(const KFileDialog&);
  965.  
  966.     void setLocationText( const QString& text );
  967.     void updateLocationWhatsThis();
  968.  
  969.     void appendExtension(KURL &url);
  970.     void updateLocationEditExtension(const QString &);
  971.     void updateFilter();
  972.  
  973.     static void initStatic();
  974.  
  975.     void setNonExtSelection();
  976.  
  977. protected:
  978.     KDirOperator *ops;
  979.     bool autoDirectoryFollowing;
  980.  
  981.     KURL::List& parseSelectedURLs() const;
  982.  
  983. protected:
  984.     virtual void virtual_hook( int id, void* data );
  985. private:
  986.     KFileDialogPrivate *d;
  987. };
  988.  
  989. #endif
  990.